home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 2000 #4 / Amiga Plus CD - 2000 - No. 4.iso / Tools / Dev / Bgui / AutoDoc / externalclass.doc < prev    next >
Encoding:
Text File  |  2000-05-09  |  5.6 KB  |  224 lines
  1. TABLE OF CONTENTS
  2.  
  3. externalclass/--background--
  4. externalclass/EXT_Class
  5. externalclass/EXT_ClassID
  6. externalclass/EXT_MinHeight
  7. externalclass/EXT_MinWidth
  8. externalclass/EXT_NoRebuild
  9. externalclass/EXT_Object
  10. externalclass/EXT_TrackAttr
  11.  
  12. externalclass/--background--
  13.  
  14.     NAME
  15.     Class:        externalclass
  16.     Superclass:    baseclass
  17.     Include File:    <libraries/bgui.h>
  18.  
  19.     FUNCTION
  20.     To provide an interface class which can be used to include third-party
  21.     gadget    classes  like  the colorwheel.gadget in a BGUI user interface.
  22.     Notification  is  currently only possible via the WM_ADDUPDATE method.
  23.     See  the  windowclass  documentation  for  more  information  on  this
  24.     subject.
  25.  
  26. externalclass/EXT_Class
  27.  
  28.     NAME
  29.     EXT_Class -- ( Class * )
  30.  
  31.     FUNCTION
  32.     Set  the  class  from  which this class needs  to  create  an  object.
  33.     This attribute expects a pointer to an already initialized class.
  34.  
  35.     NOTE
  36.     Please    note  that  _you_ are  responsible for opening and closing the
  37.     class yourself.
  38.  
  39.     DEFAULT
  40.     NULL.
  41.  
  42.     APPLICABILITY
  43.     (I).
  44.  
  45.     SEE ALSO
  46.     EXT_ClassID
  47.  
  48. externalclass/EXT_ClassID
  49.  
  50.     NAME
  51.     EXT_ClassID -- ( STRPTR )
  52.  
  53.     FUNCTION
  54.     Set  the  class  from  which  this  class  needs  to create an object.
  55.     This attribute expects a pointer to the name of the public class  like
  56.     for instance "colorwheel.gadget".
  57.  
  58.     NOTE
  59.     Please    note  that  _you_  are    responsible for opening and closing the
  60.     class library yourself.
  61.  
  62.     DEFAULT
  63.     NULL.
  64.  
  65.     APPLICABILITY
  66.     (I).
  67.  
  68.     SEE ALSO
  69.     EXT_Class
  70.  
  71. externalclass/EXT_MinHeight
  72.  
  73.     NAME
  74.     EXT_MinHeight -- ( ULONG )
  75.  
  76.     FUNCTION
  77.     As  external  classes  normally  do  not  understand the layout engine
  78.     methods  used  by  BGUI  it  has  to  be  helped  a little. With  this
  79.     attributes  you  set  the  minimum  height of the external object.  It
  80.     is very important to set reasonable values here because no checks  are
  81.     made.
  82.  
  83.     DEFAULT
  84.     0 (stupid size).
  85.  
  86.     APPLICABILTY
  87.     (I).
  88.  
  89.     SEE ALSO
  90.     EXT_MinWidth
  91.  
  92. externalclass/EXT_MinWidth
  93.  
  94.     NAME
  95.     EXT_MinWidth -- ( ULONG )
  96.  
  97.     FUNCTION
  98.     As  external  classes  normally  do  not  understand the layout engine
  99.     methods  used  by  BGUI  it  has  to  be  helped  a little. With  this
  100.     attributes  you  set  the  minimum  width  of the external object.  It
  101.     is very important to set reasonable values here because no checks  are
  102.     made.
  103.  
  104.     DEFAULT
  105.     0 (stupid size).
  106.  
  107.     APPLICABILTY
  108.     (I).
  109.  
  110.     SEE ALSO
  111.     EXT_MinHeight
  112.  
  113. externalclass/EXT_NoRebuild
  114.  
  115.     NAME
  116.     EXT_NoRebuild -- ( BOOL )
  117.  
  118.     FUNCTION
  119.     To tell the external class that the external object  does not  have to
  120.     be rebuilt after a re-size. Most classes are smart enough to  handle a
  121.     resize  of the  object  themselves  but  there  are  classes  like the
  122.     colorwheel.gadget that requires a rebuild upon a size change.
  123.  
  124.     When this   attribute    is   set  to  TRUE the class will  not rebuild
  125.     the external  object  and  you    do  not  need to use the EXT_TrackAttr
  126.     attribute to handle the object settings.
  127.  
  128.     DEFAULT
  129.     FALSE.
  130.  
  131.     APPLICABILITY
  132.     (I).
  133.  
  134.     SEE ALSO
  135.     EXT_TrackAttr, EXT_Object
  136.  
  137. externalclass/EXT_Object
  138.  
  139.     NAME
  140.     EXT_Object -- ( Object * )
  141.  
  142.     FUNCTION
  143.     Get  a    pointer  to  the "real" external object. Please note that this
  144.     pointer   changes  at  every  size  change  unless  the  EXT_NoRebuild
  145.     attribute is FALSE.
  146.  
  147.     APPLICABILITY
  148.     (G).
  149.  
  150.     SEE ALSO
  151.     EXT_NoRebuild
  152.  
  153. externalclass/EXT_TrackAttr
  154.  
  155.     NAME
  156.     EXT_TrackAttr -- ( Tag )
  157.  
  158.     FUNCTION
  159.     To  tell which attributes from the external object need to be tracked.
  160.     Because some external classes, like the colorwheel, cannot change size
  161.     once  created  it  is necessary  that the externalclass recreates the
  162.     object    at each size  change.  As this usually means  that the current
  163.     external  object  settings are lost you can tell which attributes need
  164.     to be tracked.
  165.  
  166.     The  tracked  attributes are obtained by sending the external object a
  167.     OM_GET    method    for  each  of the attributes. This means that the only
  168.     attributes  that  can be tracked are the ones that are gettable on the
  169.     external object. There is no limit as to the number of attributes that
  170.     are trackable.
  171.  
  172.     Please note however that internally the tracked attributes  are stored
  173.     in a  32bit  integer  which  means  that  tracking attributes like the
  174.     colorwheel.gadget it's WHEEL_RGB will not work.
  175.  
  176.     You can also pass attributes that are meant for the external object at
  177.     initialization time. These attributes are remembered by this class and
  178.     reused at each recreation of the external object.
  179.  
  180.     EXAMPLE
  181.     Object        *wheel;
  182.     struct Screen    *screen;
  183.  
  184.     /*
  185.     **    Create a "colorwheel.gadget" external object.
  186.     **/
  187.     wheel = ExternalObject,
  188.         EXT_MinWidth,            30,
  189.         EXT_MinHeight,            30,
  190.         EXT_ClassID,            "colorwheel.gadget",
  191.         WHEEL_Saturation,        0,
  192.         WHEEL_Screen,            screen,
  193.         EXT_TrackAttr,            WHEEL_Saturation,
  194.         EXT_TrackAttr,            WHEEL_Hue,
  195.     EndObject;
  196.  
  197.     All   tags   defined  above  are  saved  (including  the  tags    passed
  198.     automatically by the ExternalObject macro). Now a seperate copy of the
  199.     attributes to track is created.
  200.  
  201.     Once  the object needs to be  recreated the  first  thing what is done
  202.     is getting the tracked attribute values from the old object.
  203.  
  204.     Now  the  old  object  is  disposed  of  and a new one is created with
  205.     exactly the same attributes that where passed at initialization time.
  206.  
  207.     Once  this  is    accomplished the tracked attributes are set to the new
  208.     object.
  209.  
  210.     Please note that tracking attributes  is only  necessary with  classes
  211.     that require a rebuild of the object when it is resized.
  212.  
  213.     APPLICABILITY
  214.     (I).
  215.  
  216.     BUGS
  217.     The  EXT_xxx  attributes from the initialization tags are not filtered
  218.     out of the saved tag list.
  219.  
  220.     Only attributes which fit in a 32bit integer can be tracked.
  221.  
  222.     SEE ALSO
  223.     EXT_NoRebuild
  224.